Getting started

In this section we describe the first steps for using Eidos. We expect a few prerequisites, namely a React project that has the eidos package installed. This React project should also include the redux package. The goal of this guide is to fulfill the following wish from a client:

I would like to have a system in which I can create tasks and assign them to people.

Unfortunately, your system analyst was called into an important meeting, so you did not receive any more specific information. The benefit of using Eidos is that we don't yet need to know much about the tasks or the people as we can fill in these details at a later stage. For now we can quickly create our interpretation of this application and ask the client if they like it.

tip

The results of this guide can be viewed at https://github.com/bronscode/eidos-example

Configuration

We start with some configuration. We need to wrap our component tree in a global EidosProvider and connect the Eidos cache to Redux. We need to create two files: src/types.json and src/translation_en-GB.json both with an empty object {} as its contents. This will look something like the following:

import types from "./types.json";
import langEN from "./translation_en-GB.json";
...

// We create a redux store (possibly with the thunk middleware)
const store = createStore(mainReducer, applyMiddleware(thunk));

// We connect Eidos and Redux
applyEidosToRedux(store, mainReducer);


export default function GlobalProvider() {
  return (
    // As usual we wrap our component tree in the Redux provider
    <Provider store={store}>
      {/* We wrap the EidosProvider */}
      <EidosProvider
        types={types}
        locale="en-GB"
        languages={{
          "en-GB": langEN,
        }}
      >
        {/* If you make use of MUI, add this provider  */}
        <Experimental_CssVarsProvider>
          <App />
        </Experimental_CssVarsProvider>
      </EidosProvider>
    </Provider>
  );
}

We also need a configuration file for the Eidos compiler in src/eidos_config.yaml.

react:
  output: src/fields.tsx
typeInfo:
  output: src/types.json

Creating your first types

We create a file src/eidos.ts. This will be the main file in which to declare Eidos types. It is just an ordinary TypeScript file. Here we create two new types: Task and Person that represent the primary data types of this application. We also create a type Eidos. This is a special type that represents the layout of the data in the API.

import { BaseObject, List, Ref, integer, text } from "@bronscode/eidos/dist/eidos_std";

declare global {
	interface Eidos {
		tasks: List<Task>;
		persons: List<Person>;
	}

	interface Task extends BaseObject {
		name: string;
		description: text;
		difficulty: "easy" | "hard";
		assignees?: List<Ref<Person>>;
	}

	interface Person extends BaseObject {
		name: string;
		age: integer;
	}
}

Running the Eidos compiler

Each time you make an ontological change to the src/eidos.ts file, you need to re-run the Eidos compiler. This can be done by running npx eidos in the root of your project. After running this command, you can see that src/types.json contains some type metadata and that the file src/fields.tsx contains a number of React components.

Using the HUD

It is optional (but recommended) to use the default Eidos HUD (heads up display). This HUD enables the default menu and app bar together with an ErrorBoundary and Suspense component. An example of using this component can be found Here

warning

If you don't use the default HUD component, you should wrap your component tree within a React 18 Suspense component.

Creating a page

By the magic of Eidos, we can now create a list of Tasks in a TaskPagecomponent:

import { EditableTable, Page, endpoints, useSave } from "@bronscode/eidos";
import { TaskField } from "./fields";

export default function TasksPage() {
	const [tasks, controller] = useSave(endpoints.tasks);

	return (
		<Page title="Tasks">
			<EditableTable
				title="Tasks"
				values={tasks}
				controller={controller}
				DisplayComponent={TaskField}
				EditComponent={TaskField}
				emptyText="No tasks found."
				emptyValue={{}}
			/>
		</Page>
	);
}

We use a few Eidos features at once:

1. We use the useSave datahook (Read more). This obtains the tasks data from the endpoint /tasks.
2. We position this using the Page component.
3. We show an editable table using the EditableTable component (Read more).
4. This table uses the generated TaskField.

Testing the application

We can use the Eidos backend stub to test if the application works properly. Run npx npx eidos-api-stub to run a local test backend that complies with the Eidos standard. It requires a testdata.json file, that should contain at least an empty object {}.